Skip to main content

transitionedBy JQL Function Documentation

Overview​

The transitionedBy JQL function allows you to search for issues that have been transitioned to a specific status within a given time period, optionally filtered by the user who made the transition. This function is useful for tracking workflow transitions, monitoring progress, and generating reports based on status changes.

Key Features​

  • Status Transition Tracking: Find issues that were moved to a specific status.
  • Time Period Filtering: Specify a start date and optional end date to focus on transitions made within a specific time frame.
  • User Attribution: Filter transitions made by a specific user.
  • Multiple Status Support: Handle cases where multiple statuses share the same name (the function will consider all matching status IDs).
  • Comprehensive Validation: Validates all input parameters to ensure accurate results and provide clear error messages.
  • JQL Integration: Seamlessly integrates with Jira Query Language (JQL) for complex queries.

How to Use​

To use the transitionedBy function, you need to construct a JQL query that includes the transitionedBy function. The syntax is as follows:

issue in transitionedBy("subquery", "status", "start_date", ["end_date"], ["user"])

Parameters:​

  • subquery (required): A valid JQL query that defines the set of issues to evaluate.
  • status (required): The name of the status to which issues were transitioned.
  • start_date (required): The start date for the transition period in format "yyyy/MM/dd HH:mm" or "yyyy/MM/dd".
  • end_date (optional): The end date for the transition period in the same format as start_date.
  • user (optional): The username or user key of the person who made the transition.

Examples:​

  1. Finding Issues Transitioned to "In Review" within a Date Range:

    issue in transitionedBy("project = SER and statusCategory = 'In Progress'", "In Review", "2023/01/01", "2023/05/01")

  2. Finding Issues Transitioned to "Done" by a Specific User:

    issue in transitionedBy("project = SER", "Done", "2023/01/01", "2023/12/31", "jsmith")

  3. Finding Issues Transitioned to "In Progress" Since a Specific Date:

    issue in transitionedBy("project = SER", "In Progress", "2023/06/01 10:00")

  4. Finding Issues Not Transitioned to "Done" by a Specific User:

    issue not in transitionedBy("project = SER", "Done", "2023/01/01", "2023/12/31", "jsmith")

Input and Output Details​

  • Input: The transitionedBy function takes a subquery, a status name, a start date, an optional end date, and an optional username.
  • Output: The function returns a set of issues that have been transitioned to the specified status within the given time period.

Error Handling:​

The function validates all input parameters and will return clear error messages for:

  • Invalid status names
  • Invalid date formats (must be "yyyy/MM/dd HH:mm" or "yyyy/MM/dd")
  • Non-existent users
  • Invalid JQL queries

Configuration and Dependencies​

  • Ensures compatibility with the Jira Expressions API
  • Handles batched processing of issues to optimize performance and avoid API limits
  • Coordinates with Jira's changelog system to track issue transitions

Jira-Specific Information​

  • Changelog Access: The function analyzes issue changelog data, which contains historical records of all changes made to issues, including status transitions.
  • Status ID Mapping: The function automatically maps status names to their corresponding IDs, handling cases where multiple statuses have the same name.
  • User Resolution: Uses Jira's user resolution API to convert usernames to account IDs.

Performance Considerations​

  • The function analyzes all changelogs from issues matching JQL subquery. It may take significant amount of time to complete.

Conclusion​

The transitionedBy JQL function enhances the flexibility of Jira queries by allowing users to find issues based on their transition history. This powerful tool can help teams track workflow progress, monitor status changes, and analyze how work moves through their process.